4.15.1 Configuring the MyID web.oauth2 server for external identity providers

You must configure your external identity provider (for example, Microsoft Entra), then configure the web.oauth2 server to recognize the external system as an external identity provider.

For details, see the Setting up an external identity provider section in the MyID Authentication Guide.

Note: You can configure your system for multiple external identity providers. Each configured external identity provider appears in the list of options within the Self-Service App. Note, however, that you can restrict the list of external identity providers available for the Self-Service App; see the AllowedLogonMechanismIds option in section 4.15.4, Configuring the MyID web services for external identity providers.

4.15.2 Configuring the logon priority for external identity providers

You can specify the priority of the available logon mechanisms, including external identity providers.

See the Logon Priority page (Security Settings) section in the Administration Guide for details.

4.15.3 Configuring the credential profile self-service unlock settings for external identity providers

You can include the External Logon authentication method in the list of available authentication methods specified in the credential profile for self-service unlock.

See the Self-Service Unlock Authentication section in the Administration Guide for details.

4.15.4 Configuring the MyID web services for external identity providers

You must edit the myid.config file for the MyIDProcessDriver web service to specify the allowed hosts and allowed logon mechanisms. By default, this file is on the web services server in the following folder:

C:\Program Files\Intercede\MyID\SSP\MyIDProcessDriver\

Add the following lines to the <MyIDSettings> section:

<add key="AllowedHosts" value="<urls>"/>
<add key="AllowedLogonMechanismIds" value="<logonids>"/>

where:

• <urls> – a comma-separated list of allowed MyID web server URLs.

  This is to prevent host header injection; for example, when building the URLs that are sent to the Self-Service App for this feature. The Self-Service App allows you to attempt authentication with an external identity provider if your MyID web server URL matches any of the URLs in the AllowsHosts setting.

• <logonids> – a comma-separated list of allowed logon mechanisms.

  You can use the following values:

  • 101 – corresponds to Microsoft Entra ID.

  • 121 – corresponds to External IDP 1.

  • 122 – corresponds to External IDP 2.

  • 123 – corresponds to External IDP 3.

  These are the logon mechanisms that appear on the "Authenticate using an External Provider" screen in the Self-Service App. Note that you must also have the corresponding logon mechanism enabled on the Logon Mechanisms tab of the Security Settings workflow.

  This allows you to restrict the logon mechanisms available in the Self-Service App; for example, you may have two external identity providers configured for your MyID system, but want to allow only one of them to be used in the Self-Service App.

For example:

<MyIDSettings>
    ...
    <add key="AllowedHosts" value="https://myserver.example.com"/> 
    <add key="AllowedLogonMechanismIds" value="101,121"/> 
</MyIDSettings>

4.15.5 Using an external identity provider within the Self-Service App

Once you have configured your system, when you collect a job, change your security phrases, or reset your PIN, you can use the external identity provider to provide authentication to MyID.

If you have more than one external identity provider configured, you can select which one to use on this screen:

When you click the link for the identity provider, the default web browser opens, and the Self-Service App waits for the response.

If you experience any issues launching the browser (for example, if the browser does not open, or you want to use a different browser) you can copy the link text from the Self-Service App screen and paste it into your browser's address bar manually.

Follow the instructions on the web page to authenticate.

If you cannot authenticate, close the browser window and click Cancel in the Self-Service App.

Note: Make sure you authenticate using the correct user account for the person who needs to use the Self-Service App feature.

Click the button to return to the Self-Service App once you have authenticated. The browser window attempts to close after a short delay.

Note: If the browser window does not close, due to the browser or other external issues, close the window manually and return to the Self-Service App.

4.15.6 Configuring the delay for closing the browser logon window

When you click the link on the browser logon window to return to the Self-Service App, after a short delay, the browser window closes. This allows time for the browser logon window to inform the MyID web server that the authentication was successful.

If necessary, you can adjust the delay time:

1. On the MyID web server, as an administrator, open the appsettings.Production.json file in a text editor.

   By default, this is:

   C:\Program Files\Intercede\MyID\web.oauth2\appsettings.Production.json

   This file is the override configuration file for the appsettings.json file for the web service. If this file does not already exist, you must create it in the same folder as the appsettings.json file.

2. In the MyID section, edit the SsaLaunchWindowCloseDelay option.

   Copy

   "MyID": {
       "SsaLaunchWindowCloseDelay":  10000
   },
   

   If this option does not exist, you must add it.

   Set the value to the number of milliseconds you want to wait before closing the browser logon window. Setting this value too low may result in the MyID web server not receiving a notification that the authentication was successful.

   The default setting in the appsettings.json file is 10000 (10 seconds).

3. Save the appsettings.Production.json file.

4. Recycle the web service app pool:

   1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
   2. Right-click the myid.web.oauth2.pool application pool, then from the pop-up menu click Recycle.

   This ensures that the web service has picked up the changes to the configuration file.

4.15.7 Compatibility with older versions of MyID

This feature requires the MyID Self-Service App version SSP-3.21.1000.1 or later. This also means that by default you cannot use this version of the Self-Service App with MyID servers older than MyID 12.12. If you need to use this version of the Self-Service App with MyID servers older than MyID 12.12, you must set a client-side configuration option. See section 8.3, Compatibility issues.

4.15.8 Troubleshooting external identity providers

You may see the following error messages when attempting to authenticate with external identity providers:

• 890811 – Unable to determine server address

  Check that the AllowedHosts setting is correct. The setting must match the URL used for the MyID web server.

  See section 4.15.4, Configuring the MyID web services for external identity providers.

• 890812 – Unable to continue, invalid authenticated user

  You have attempted to carry out authentication using an external identity provider, but the user account with which you have authenticated is not the target user for the job.